Skip to content

feat: support BackedEnum values in database binds#10256

Open
memleakd wants to merge 2 commits into
codeigniter4:4.8from
memleakd:feat/query-builder-backed-enums
Open

feat: support BackedEnum values in database binds#10256
memleakd wants to merge 2 commits into
codeigniter4:4.8from
memleakd:feat/query-builder-backed-enums

Conversation

@memleakd
Copy link
Copy Markdown
Contributor

Description

This PR adds support for PHP BackedEnum values in database escaping, query bindings, and escaped Query Builder values.

It was inspired by @maniaba's forum post and #10223.

For apps that use native PHP enums for domain values, this makes database code a bit nicer to write:

$db->table('users')
    ->where('status', UserStatus::Active)
    ->get();

CodeIgniter will use the enum's backing value when escaping it, so string-backed enums are treated like strings and int-backed enums are treated like integers.

This avoids repeating ->value at every query call site, while keeping raw SQL and escape-disabled values in the caller's control.

The implementation is intentionally small: enum cases are unwrapped during database escaping, so regular query bindings and escaped Query Builder values use the same existing path.

Checklist:

  • Securely signed commits
  • Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
  • Unit testing, with >80% coverage
  • User guide updated
  • Conforms to style guide

- Allow database escaping to use BackedEnum backing values
- Support BackedEnum values in query bindings and Query Builder binds
- Add focused tests and user guide examples

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>
@github-actions github-actions Bot added the 4.8 PRs that target the `4.8` branch. label May 31, 2026
Copy link
Copy Markdown
Contributor

@datamweb datamweb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR look good to me.

Comment thread tests/system/Database/Builder/WhereTest.php
Copy link
Copy Markdown
Member

@michalsn michalsn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like native prepared statements are not supported.

$query = $db->prepare(...);
$query->execute(StatusEnum::ACTIVE);

Comment thread tests/system/Database/Builder/InsertTest.php
Comment thread tests/system/Database/Builder/WhereTest.php
@memleakd
Copy link
Copy Markdown
Contributor Author

memleakd commented Jun 1, 2026

Seems like native prepared statements are not supported.

Thanks for the review. I pushed an update for adding prepared query support, object input coverage, and the SQL assertion helper.

@datamweb
Copy link
Copy Markdown
Contributor

datamweb commented Jun 1, 2026

@memleakd Could you please implement the assertSqlEquals() and its usage in a separate Pull Request?
Also, please make sure to update the testing documentation accordingly here:
https://codeigniter4.github.io/userguide/testing/overview.html#id10

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>
@memleakd memleakd force-pushed the feat/query-builder-backed-enums branch from 0f8817f to 7314bed Compare June 1, 2026 20:50
@memleakd
Copy link
Copy Markdown
Contributor Author

memleakd commented Jun 1, 2026

@memleakd Could you please implement the assertSqlEquals() and its usage in a separate Pull Request?

That was my natural first instinct too, but I somehow got the impression from the review wording that it might be preferred here 😅 Anyway, I reverted it now, so this PR is clean again and only keeps the enum-related changes.

Copy link
Copy Markdown
Member

@michalsn michalsn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wondering whether we should throw a clear InvalidArgumentException when a backed enum is used with escaping disabled. However, since this behavior is documented, the current implementation should be fine. We can revisit this if users start complaining.

@michalsn michalsn added the enhancement PRs that improve existing functionalities label Jun 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

4.8 PRs that target the `4.8` branch. enhancement PRs that improve existing functionalities

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants